Skip to content

external api: a token-authenticated MCP surface for outside agents (#150) - #151

Merged
Lexus2016 merged 1 commit into
mainfrom
feat/external-mcp-server-150
Nov 21, 2026
Merged

Lexus2016 merged 1 commit into
mainfrom
feat/external-mcp-server-150

Conversation

@Lexus2016

Copy link
Copy Markdown
Owner

Closes #150 (stage 1 — projects and tasks; chats stay stage 2 as agreed in the issue).

Why

CCS was an MCP client only. An outside agent could drive the Kanban board solely through /api/internal/task-manager, with a per-process secret that changes on every restart, no notion of projects, and no contract that survives a release. The issue asked for a supported entry point; this is it.

What is added

mcp-ccs.js — a self-contained stdio MCP server: zero dependencies, no sibling files, http or https, configured by CCS_URL (path prefixes supported) and CCS_TOKEN. Tools: list_projects, list_tasks, get_task, get_task_result, create_task, cancel_task.

Tokens (api-token.js) — dedicated, not the internal secret:

  • plaintext shown once, only a SHA-256 stored in data/api-tokens.json (mode 0600);
  • scopes read (list/read) and full (also create/cancel) — creating a task runs claude, so a monitoring client can stay read-only;
  • revocable without logging the owner out, effective on the next request, max 20;
  • minted from a shell (node scripts/api-token.js create|list|revoke, the Docker path) or from a logged-in session (/api/api-tokens).

/api/external/v1/* — me, projects, tasks, tasks/:id, tasks/:id/result, tasks/:id/cancel. Registered in front of auth.authMiddleware so an external token reaches nothing else: no chats, files, settings or terminals. Any request carrying an Origin header is refused (browsers attach one; stdio clients never do).

create_task semantics — project is required (id or exact name, ambiguous names refused with the candidate ids) and nothing is inherited: an outside caller has no parent task whose workdir could be borrowed. status defaults to backlog, so a card lands on the board and nothing runs until the caller asks for todo; the task gets its own git worktree, like a UI card.

Verification

  • test/external-api.test.js — boots the server and drives the REST surface end to end: 401 without a token, Origin refused, read token cannot create/cancel, missing/unknown project refused, backlog stays backlog, todo accepted with a far-future schedule, cancel + idempotence + the done guard, revocation kills the token on the next call. Then it runs mcp-ccs.js as a real stdio client (initialize → tools/list → tools/call) against that server, including the read-only and missing-token paths.
  • test/api-token.test.js — plaintext never on disk, 0600, sha256 on disk, scope validated (never coerced), revocation immediate, malformed file fails closed, the 20-token cap.
  • test/asar-helpers.test.js — mcp-ccs.js is deliberately the one mcp-*.js with no helperPath() spawn site (it is a client for an external host, not a helper the server starts); the check now says so instead of tripping on it.
  • test/task-text-limit.test.js — the new external write path is counted among the shared-limit writes, and mcp-ccs.js's inlined literal is pinned to task-text-limit.js.

Local full suite: every test file run individually against this branch and against main (32fa765) — failures are identical between the two and are environment-only (no tmux here, and task-backlog.test.js's second server on localhost:4553 does not come up in this container); the list is in a review comment.

Docs: docs/EXTERNAL-API.md (token setup, client config for Claude Code and MCPHub, tool table, REST table, boundaries).

Not in this PR

Chats: create_chat can reuse POST /api/sessions, but send_message / get_messages / stop_turn have no documented contract — the web UI drives turns over the app WebSocket. That design is stage 2.

)

An agent outside CCS (another Claude Code session, MCPHub, a monitoring script)
could only reach the internal /api/internal/task-manager door, with a per-process
secret that changes on every restart, no projects and no contract.

This is stage 1 of #150 — projects and tasks. Chats stay stage 2: send_message and
stop_turn need a documented server contract before a wrapper can expose them.

What is added:

- mcp-ccs.js: a self-contained stdio MCP server (zero dependencies, http or https,
  CCS_URL + CCS_TOKEN) exposing list_projects, list_tasks, get_task,
  get_task_result, create_task and cancel_task.
- api-token.js: scoped, revocable tokens. The plaintext is shown once, only its
  SHA-256 is stored in data/api-tokens.json (0600); scopes read|full; at most 20.
- /api/external/v1/*: the whole external contract, registered in front of the
  session wall so an external token cannot reach chats, files, settings or
  terminals. A request carrying an Origin header is refused.
- create_task requires an explicit project and defaults to status "backlog": an
  outside caller never inherits a workdir and never starts a run by accident.
- scripts/api-token.js: create/list/revoke from a shell, which is the Docker path.

Tests: test/api-token.test.js (store: hashed at rest, revocation immediate, a
malformed file fails closed) and test/external-api.test.js, which drives the REST
surface and then runs mcp-ccs.js as a real stdio MCP client — initialize,
tools/list, tools/call — against a booted server. Docs: docs/EXTERNAL-API.md.
@chatgpt-codex-connector

Copy link
Copy Markdown
Codex Review Summary: ❌ Failed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ❌ Failed 2026-11-21T09:11:40.214545Z
We couldn’t complete this review. Comment @codex review to try again.
44f0307 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

@Lexus2016
Lexus2016 merged commit b8a9e65 into main Nov 21, 2026
3 checks passed
@Lexus2016
Lexus2016 deleted the feat/external-mcp-server-150 branch November 21, 2026 09:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Expose CCS as an MCP server (drive chats and tasks from an external Claude)

1 participant